This vignette gives an overview of the USTerritoryMapping package, which is seeks to make creating categorical choropleth maps of the US that include the US territories a little bit easier!
First load the package.
library(USTerritoryMapping)To use this package, you will need to have a dataframe with (1) a categorical variable coded as a factor and (2) a column with the two-letter US Postal Service code for each state and territory (e.g., VA for Virginia or VI for Virgin Islands). fipscodes.rda is provided to facilitate #2.
For this vignette, we’ll be using the two provided datasets census.uninsured19 and cdc.cvd. census.uninsured19 provides an example of a dataset with complete data for all states and territories, while cdc.cvd is missing values for territories.
data(census.uninsured19)
data(cdc.cvd)We can see that each dataset has these two components. In census.uninsured19: (1) “Percent.Cat” which is the Percentage Ages 19 or Under with No Health Insurance, and (2) “LocationAbbr”.
class(census.uninsured19$Percent.Cat)
#> [1] "factor"
table(census.uninsured19$Percent.Cat)
#>
#> Less than 5% 5% to <10% 10% or Greater
#> 29 22 5
head(census.uninsured19$STUSPS)
#> [1] "PA" "CA" "WV" "UT" "NY" "DC"In cdc.cvd: (1) “data.cat” which is the CVD mortality rate per 100,000 persons, and (2) “LocationAbbr”.
class(cdc.cvd$data.cat)
#> [1] "character"
table(cdc.cvd$data.cat)
#>
#> Q1 (166 to < 198) Q2 (198 to < 215) Q3 (215 to < 248) Q4 (248 to 326)
#> 13 13 12 13
head(cdc.cvd$LocationAbbr)
#> [1] "AL" "AK" "AZ" "AR" "CA" "CO"Start by defining the fill category colors with their factor labels.
colors.census <- c("Less than 5%" = "#feebe2",
"5% to <10%" = "#f768a1",
"10% or Greater" = "#7a0177")map1_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
territory_label_color = "black",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
save.filepath = "saved-maps/map1-uninsure.png")Let’s say we wanted to add a border to highlight specific states. We’ll first define a vector of IDs and then use the border_ids parameter.
border <- c("OR", "WI", "VA", "VI")
map1_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
border_ids = border,
border_color = "red",
border_linewidth = 1,
save.filepath = "saved-maps/map1-uninsure2.png")We highlight the additional option of removing the inset box by specifying inset_box_color = "white". We also highlight the additional option of removing the territory labels by specifying territory_label_color = "white".
colors.cdc <- c("Q1 (166 to < 198)" = "#ffffcc",
"Q2 (198 to < 215)" = "#a1dab4",
"Q3 (215 to < 248)" = "#41b6c4",
"Q4 (248 to 326)" = "#225ea8")
map1_categorical(data = cdc.cvd,
join_var = "LocationAbbr",
fill_var = "data.cat",
fill_color = colors.cdc,
fill_linewidth = 1.2,
fill_linecolor = "black",
inset_box_color = "white",
territory_label_color = "white",
legend_name = "CVD Mortality per 100,000",
border_ids = border,
border_color = "red",
border_linewidth = 1.5,
save.filepath = "saved-maps/map1-cvd.png") You may also want a map with the territory labels filled by value rather than the geometries.
colors.census <- c("Less than 5%" = "#feebe2",
"5% to <10%" = "#f768a1",
"10% or Greater" = "#7a0177")
border <- c("OR", "WI", "VA", "VI")
map2_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
border_ids = border,
border_color = "red",
border_linewidth = 1,
save.filepath = "saved-maps/map2-uninsure.png")Note that the territory labels cannot be highlighted, even when specified in the border ID vector.
colors.cdc <- c("Q1 (166 to < 198)" = "#ffffcc",
"Q2 (198 to < 215)" = "#a1dab4",
"Q3 (215 to < 248)" = "#41b6c4",
"Q4 (248 to 326)" = "#225ea8")
map2_categorical(data = cdc.cvd,
join_var = "LocationAbbr",
fill_var = "data.cat",
fill_color = colors.cdc,
fill_linewidth = 1.2,
fill_linecolor = "black",
inset_box_color = "white",
legend_name = "CVD Mortality per 100,000",
border_ids = border,
border_color = "red",
border_linewidth = 1.5,
save.filepath = "saved-maps/map2-cvd.png")